home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / g_man / cat3 / OpenGL-GLC / glcintro.z / glcintro
Text File  |  1998-10-20  |  16KB  |  397 lines
  1.  
  2.  
  3.  
  4. ggggllllccccIIIInnnnttttrrrroooo((((3333GGGG))))              OOOOppppeeeennnnGGGGLLLL CCCChhhhaaaarrrraaaacccctttteeeerrrr RRRReeeennnnddddeeeerrrreeeerrrr               ggggllllccccIIIInnnnttttrrrroooo((((3333GGGG))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ggggllllccccIIIInnnnttttrrrroooo - Introduction to the OpenGL Character Renderer
  10.  
  11.  
  12.  
  13. DDDDOOOOCCCCUUUUMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  14.      The most authoritative documentation on GLC is the GLC specification
  15.      document, which is included in this release in PostScript form.  If you
  16.      install the software product gl_dev.sw.samples, the GLC specification
  17.      will be installed as /usr/share/src/OpenGL/teach/glc/glcspec.ps.
  18.  
  19.  
  20. OOOOVVVVEEEERRRRVVVVIIIIEEEEWWWW
  21.      The OpenGL Character Renderer (GLC) is a subroutine library that provides
  22.      OpenGL programs with character rendering services.
  23.  
  24.      A GLC context is an instantiation of the GLC state machine. A GLC client
  25.      is a program that uses both OpenGL (henceforth, "GL") and GLC.  When a
  26.      client thread issues a GLC command, the thread's current GLC context
  27.      executes the command.
  28.  
  29.      To render a character, a GLC client issues the command
  30.  
  31.          glcRenderChar(GLint inCode);
  32.  
  33.      GLC then goes through these steps:
  34.  
  35.      1.  GLC finds a font that maps inCode to a character such as LATIN
  36.          CAPITAL LETTER A.
  37.  
  38.      2.  GLC uses one or more glyphs from the font to create a graphical
  39.          layout that represents the character.
  40.  
  41.      3.  GLC issues a sequence of GL commands to draw the layout.
  42.  
  43.      A font is a stylistically consistent set of glyphs that can be used to
  44.      render some set of characters. Each font has a family name (e.g.
  45.      Palatino) and a state variable that selects one of the faces (e.g.
  46.      Regular, Bold, Italic, Bold Italic) that the font contains. A typeface is
  47.      the combination of a family and a face (e.g.  Palatino Bold).
  48.  
  49.      A font is an instantiation of a master. A master is a representation of
  50.      the font that is stored outside of GLC in a standard format such as Type
  51.      1.
  52.  
  53.      A catalog is a file containing a list of master file names.  A list of
  54.      catalog names (GLC_CATALOG_LIST) defines the list of masters that can be
  55.      instantiated in a GLC context.  When a GLC context is created,
  56.      GLC_CATALOG_LIST initially contains one name:
  57.      ("/usr/lib/X11/fonts/Type1/fonts.dir").
  58.  
  59.      By default, GLC interprets all character codes as elements of the
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ggggllllccccIIIInnnnttttrrrroooo((((3333GGGG))))              OOOOppppeeeennnnGGGGLLLL CCCChhhhaaaarrrraaaacccctttteeeerrrr RRRReeeennnnddddeeeerrrreeeerrrr               ggggllllccccIIIInnnnttttrrrroooo((((3333GGGG))))
  71.  
  72.  
  73.  
  74.      Universal Coded Set (UCS) defined by ISO 10646-1:1993.
  75.  
  76.      The interpretation of arrays of character codes of type GLCchar in the
  77.      GLC API is determined by the value of the GLC context state variable
  78.      GLC_STRING_TYPE. The values GLC_UCS1, GLC_UCS2, and GLC_UCS4 specify that
  79.      each array element is a UCS code of type GLubyte, GLushort, or GLint,
  80.      respectively. The initial value of GLC_STRING_TYPE is GLC_UCS1.
  81.  
  82.      Before issuing a GLC rendering command, a client must issue GL commands
  83.      directly to establish a GL state such that the GL commands issued by GLC
  84.      produce the desired result. For example, before issuing a glcRenderChar
  85.      command, a client may issue glColor and glRasterPos commands to establish
  86.      the color and origin of the resulting layout.
  87.  
  88.      Before issuing any GLC commands, the client must create a GL context and
  89.      make it current.
  90.  
  91.  
  92.    LLLLaaaayyyyoooouuuutttt
  93.      Glyph coordinates are defined in em units and are transformed during
  94.      rendering to produce the desired mapping of the glyph shape into the GL
  95.      window coordinate system.
  96.  
  97.      In addition to commands for rendering, the GLC API includes measurement
  98.      commands that return certain metrics (currently the bounding box and the
  99.      baseline) for the layout.
  100.  
  101.      Since the focus of GLC is on rendering and not modeling, the GLC API does
  102.      not provide access to glyph shape data.
  103.  
  104.  
  105. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  106.      The following ISO C code fragment uses GL and GLC to render the character
  107.      LATIN CAPITAL LETTER A in red at (100, 100) using a default typeface at a
  108.      scale of 24 pixels per em. In this example, GLC issues a glBitmap command
  109.      to draw the layout.
  110.  
  111.          glcContext(glcGenContext());
  112.          glcScale(24.f, 24.f);
  113.          glColor3f(1.f, 0.f, 0.f);
  114.          glRasterPos2f(100.f, 100.f);
  115.          glcRenderChar(`A');
  116.  
  117.      In the following example, GLC renders the string "Hello, world!" in red
  118.      24 pixel Palatino Bold at a rotation of 30 degrees, starting at (100,
  119.      100).
  120.  
  121.          glcContext(glcGenContext());
  122.          glcFont (glcNewFontFromFamily(1, "palatino"));
  123.          glcFontFace(1, "bold");
  124.          glcScale(24.f, 24.f);
  125.          glcRotate(30.f);
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ggggllllccccIIIInnnnttttrrrroooo((((3333GGGG))))              OOOOppppeeeennnnGGGGLLLL CCCChhhhaaaarrrraaaacccctttteeeerrrr RRRReeeennnnddddeeeerrrreeeerrrr               ggggllllccccIIIInnnnttttrrrroooo((((3333GGGG))))
  137.  
  138.  
  139.  
  140.          glColor3f(1.f, 0.f, 0.f);
  141.          glRasterPos2f(100.f, 100.f);
  142.          glcRenderString("Hello, world!");
  143.  
  144.  
  145. NNNNOOOOTTTTEEEESSSS
  146.      -   The current implementation of GLC implements only a subset of the
  147.          GLC specification.
  148.  
  149.      -   The implementation specific constants for the current
  150.          implementation are as follows: GLC_EXTENSIONS="",
  151.          GLC_RELEASE="IRIX 6.2", GLC_VENDOR="SGI".
  152.  
  153.      -   The only language bindings that are currently available for GLC
  154.          are C and C++.
  155.  
  156.      -   The GLC API is designed to handle 10646-1 codepoints larger than
  157.          255, but support for these codepoints is not implemented in the
  158.          current release.
  159.  
  160.      -   The GLC API is designed to support a variety of master formats,
  161.          but the current implementation supports only masters in PostScript
  162.          Type 1 text format (.pfa files).
  163.  
  164.      -   In the current implementation, a catalog file must be in the
  165.          format generated by the X Window System utility program
  166.          mkfontdir(1).  Future releases may use a different catalog file
  167.          format.
  168.  
  169.      -   The current implementation maps the Type 1 .pfa files in
  170.          /usr/lib/X11/fonts/Type1 into master objects that are visible
  171.          through the GLC API.  A group of .pfa files from a single typeface
  172.          family will be mapped into a single GLC master object that has
  173.          multiple faces.  For example, the files AvantGarde-Book.pfa,
  174.          AvantGarde-BookOblique.pfa, AvantGarde-Demi.pfa, and
  175.          AvantGarde-DemiOblique.pfa are visible through the GLC API as a
  176.          single master with GLC_VENDOR="Adobe", GLC_FAMILY="ITC Avant Garde
  177.          Gothic", GLC_MASTER_FORMAT="Type 1", GLC_FACE_COUNT=4, and
  178.          GLC_FACE_LIST=("Book", "Book Oblique", "Demi", Demi Oblique").
  179.  
  180.      -   Future releases may provide mechanisms to control the ordering of
  181.          masters in a catalog and the ordering of each master's face list.
  182.          Future releases may also change the default orderings of masters
  183.          and faces.  Therefore, GLC clients should not depend on any
  184.          particular ordering of masters or faces.
  185.  
  186.      -   The GLC specification requires that a master's character map (and
  187.          hence a font's initial character map) must be strictly based on
  188.          10646-1.  A GLC client that wants to use a different character
  189.          mapping must issue a sequence of glcFontMap commands to obtain the
  190.          required mapping.  Subroutines that issue glcFontMap command
  191.          sequences to set up the most popular mappings are available in
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. ggggllllccccIIIInnnnttttrrrroooo((((3333GGGG))))              OOOOppppeeeennnnGGGGLLLL CCCChhhhaaaarrrraaaacccctttteeeerrrr RRRReeeennnnddddeeeerrrreeeerrrr               ggggllllccccIIIInnnnttttrrrroooo((((3333GGGG))))
  203.  
  204.  
  205.  
  206.          source code form (see below).
  207.  
  208.          The argument inCharName to glcFontMap is the 10646-1 name of the
  209.          character to be mapped, e.g. "LATIN CAPITAL LETTER A".  These
  210.          names are documented in the Unicode 2.0 standard.
  211.  
  212.          The non 10646-1 character mappings that are used most commonly
  213.          with Type 1 masters are Adobe Standard, Adobe Symbol, and Adobe
  214.          Zapf Dingbats.  The information needed to set up these mappings
  215.          via glcFontMap commands can be found in the Unicode 2.0 standard.
  216.  
  217.          For example, the Adobe Zapf Dingbats encoding maps the code 0xD5
  218.          to U+2192.  The Unicode 2.0 name of this character is RIGHTWARDS
  219.          ARROW.  To set up the Adobe encoding for this character, issue the
  220.          command
  221.  
  222.          glcFontMap(f, 0xD5, "RIGHTWARDS ARROW");
  223.  
  224.          In general, GLC uses 10646-1 character names, not Adobe glyph
  225.          names.  If, however, a master supports characters that are not
  226.          contained in 10646-1, GLC uses the Adobe glyph names for these
  227.          characters.  For example, the ligature glyphs "fi" and "fl" are
  228.          not contained in 10646-1 and hence are never mapped in a master's
  229.          character map, but they may be contained in a master's
  230.          GLC_CHAR_LIST and can be mapped via glcFontMap.
  231.  
  232.          If your application uses Adobe character mappings, install the
  233.          software product gl_dev.sw.samples and use the subroutines in
  234.          /usr/share/src/OpenGL/tools/glc/fontmap.c to issue the sequence of
  235.          glcFontMap commands that is necessary to establish the desired
  236.          mappings.
  237.  
  238.  
  239. BBBBUUUUGGGGSSSS
  240.      The following is a list of known GLC bugs in the current release.
  241.      Application developers should take care to not write code that depends on
  242.      the presence of these bugs, which will be removed in a future release.
  243.  
  244.      -   The current implementation has been tested with the Type 1 master
  245.          files that SGI ships, but may not work properly with third party
  246.          Type 1 master files.
  247.  
  248.      -   The current implementation does not work properly with the
  249.          following SGI-shipped typefaces: Adobe Carta, Adobe Copal
  250.          Decorated.  Using these typefaces in GLC may lead to program
  251.          termination.
  252.  
  253.      -   In the current implementation, the following commands raise
  254.          GLC_STATE_ERROR and return zero: glcGetFontMasterArray,
  255.          glcNewFontFromMasterArray.
  256.  
  257.      -   In the current implementation, the following command raises
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. ggggllllccccIIIInnnnttttrrrroooo((((3333GGGG))))              OOOOppppeeeennnnGGGGLLLL CCCChhhhaaaarrrraaaacccctttteeeerrrr RRRReeeennnnddddeeeerrrreeeerrrr               ggggllllccccIIIInnnnttttrrrroooo((((3333GGGG))))
  269.  
  270.  
  271.  
  272.          GLC_PARAMETER_ERROR: glcRenderStyle(GLC_TEXTURE)
  273.  
  274.      -   In the current implementation, the following state variables can
  275.          be set and retrieved, but they have no effect: GLC_MIPMAP,
  276.          GLC_RESOLUTION.
  277.  
  278.      -   The current implementation ignores the state variable
  279.          GLC_RESOLUTION and computes all metrics at 1000 pixels per em.
  280.          When rendering with GLC_RENDER_STYLE == GLC_BITMAP at lower
  281.          resolutions, returned metrics may not match the rendered layout.
  282.  
  283.      -   In the current implementation, the state variable
  284.          GLC_TEXTURE_OBJECT_LIST always contains zero elements.
  285.  
  286.      -   In the current implementation, the master/font attribute
  287.          GLC_VERSION) is always the empty string ("").
  288.  
  289.      -   In the current implementation, the character maps of masters
  290.          contain no entries larger than 255, and the following commands
  291.          raise GLC_PARAMETER_ERROR if inCode is greater than 255:
  292.          glcFontMap, glcGetFontMap, glcGetMasterMap.
  293.  
  294.          As a result, most of the characters supported by the masters
  295.          Symbol and ITC Zapf Dingbats, which have 10646-1 codepoints that
  296.          are larger than 255, are not mapped.  To use these characters,
  297.          issue a sequence of glcFontMap commands to map codes smaller than
  298.          256 to these characters.  Subroutines that do this for you are
  299.          available in source code form (see above).
  300.  
  301.      -   In the current implementation, the following commands truncate all
  302.          incoming character codes to the low order 8 bits (the specified
  303.          behavior is to truncate to the low order 31 bits):
  304.          glcAppendCatalog, glcPrependCatalog, glcFontFace, glcFontMap,
  305.          glcNewFontFromFamily.
  306.  
  307.      -   The current implementation does not conform to the specified
  308.          behavior of rendering a character in the form \<hexcode> if a
  309.          font that maps the character cannot be found.
  310.  
  311.      -   In the current implementation, the GLC current-context state
  312.          variable is per-process, not per-thread.
  313.  
  314.      -   In the current implementation, the GLC current-error variable is
  315.          stored in the current GLC context, not in thread-local storage.
  316.  
  317.      -   The current implementation does not conform to the specified
  318.          behavior of issuing the commands glGetString(GL_VERSION) and
  319.          glGetString(GL_EXTENSIONS) when the command glcContext is
  320.          executed.
  321.  
  322.      -   The current implementation ignores the following environment
  323.          variables: GLC_CATALOG_LIST, GLC_LIST_SEPARATOR.
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. ggggllllccccIIIInnnnttttrrrroooo((((3333GGGG))))              OOOOppppeeeennnnGGGGLLLL CCCChhhhaaaarrrraaaacccctttteeeerrrr RRRReeeennnnddddeeeerrrreeeerrrr               ggggllllccccIIIInnnnttttrrrroooo((((3333GGGG))))
  335.  
  336.  
  337.  
  338. FFFFIIIILLLLEEEESSSS
  339.          /usr/include/GL/glc.h
  340.          /usr/lib/libGLC.so
  341.          /usr/lib32/libGLC.so
  342.          /usr/lib64/libGLC.so
  343.          /usr/lib/X11/fonts/Type1/fonts.dir
  344.          /usr/lib/X11/fonts/Type1/*.pfa
  345.          /usr/share/src/OpenGL/tools/glc/fontmap.c
  346.          /usr/share/src/OpenGL/tools/glc/glcspec.ps
  347.  
  348.  
  349. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  350.      glcRenderChar, glintro
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.                                                                         PPPPaaaaggggeeee 6666
  394.  
  395.  
  396.  
  397.